home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.084 < prev    next >
Encoding:
Text File  |  1990-08-23  |  11.5 KB  |  238 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #84:    TaskMaster Madness
  8.  
  9. Written by:    C.K. Haun <TR>                                       July 1990
  10.  
  11. This Technical Note discusses the enhancements made to TaskMaster in System 
  12. Software 5.0.
  13. _____________________________________________________________________________
  14.  
  15. TaskMaster has been expanded to handle extended control actions and give you 
  16. more information about events in System Software 5.0.  This Note discusses 
  17. some features of the expanded TaskMaster and TaskMasterDA, and how you can 
  18. best exploit the new features in your applications.
  19.  
  20.  
  21. Stop Making It So Difficult
  22.  
  23. Developers just want to work too hard.  You get a neat new thing like the 
  24. expanded TaskMaster, and you still want to do all the work yourself.  The new 
  25. TaskMaster does nearly everything for you, as long as you treat it correctly.
  26.  
  27. What this means is you do not have to call FindControl, TrackControl, TEIdle, 
  28. LEKey, handle keystrokes for controls, keep track of click counts, or any of 
  29. the other mundane event management tasks unless you specifically want to 
  30. perform actions that TaskMaster does not perform.  For the standard controls 
  31. and situations this means that you do not have to do anything.
  32.  
  33. The magic keys to this life of freedom and ease are the five newly defined 
  34. taskMask flag bits, labeled in the interfaces as tmContentControls, 
  35. tmControlKey, tmControlMenu, tmMultiClick and tmIdleEvents.  This Note looks 
  36. at what the new bits do for you, but first a word of warning.
  37.  
  38. Warning:  If you set any of these new bits, TaskMaster assumes you are 
  39.           using the new extended task record.  This means that you 
  40.           cannot just go into an older program and set these bits and 
  41.           expect your program to work successfully.  You also must 
  42.           allocate the additional space for the extended portion of 
  43.           the task record.  If you do not, TaskMaster puts task data 
  44.           in areas that you do not expect, and Bad Things happen.
  45.  
  46.  
  47. Bits 'o This, Bits 'o That
  48.  
  49. Click Bits
  50.  
  51. tmMultiClick tells TaskMaster to keep the new "click information" fields in 
  52. the extended task record updated.  This allows you to have TaskMaster keep 
  53. track of multiclick events; the wmClickCount field is one, two or three 
  54. depending on whether the last action was a single, double, or triple click.  
  55. In fact, if you can click your mouse button fast enough, you can time 
  56. quadruple clicks, sextuple clicks, or as high as you want, although anything 
  57. over triple-clicking is nearly impossible for users to consistently manage.  
  58. wmClickCount just gets incremented by one when the click falls within the 
  59. double time interval.  wmLastClickTick is updated with the system tick value 
  60. at last click.  wmLastClickPt contains the location of the last mouse click.  
  61. TaskMaster calls GetDblTime internally to determine the correct time intervals 
  62. for these values.
  63.  
  64. Idle Bits
  65.  
  66. tmIdleEvents tells TaskMaster to call the idle routines for controls that need 
  67. idle events, like TextEdit controls and LineEdit controls.  This also means 
  68. that only the active control is blinking a cursor, since TaskMaster is working 
  69. with the target bits of the extended control records to keep track of which 
  70. TextEdit or LineEdit control is active and switching the target control in 
  71. response to mouse clicks and Tab keypresses.  This is also the area where you 
  72. tell TaskMaster how to highlight your window controls.  Using the Control 
  73. Manager calls MakeNextCtlTarget and MakeThisCtlTarget allows you to specify 
  74. which LineEdit or TextEdit control is active.  You can use these calls to 
  75. highlight input errors the user has made.  For example, if someone has entered 
  76. text in a LineEdit control that requires a number, you can alert the user if 
  77. he enters non-numeric characters with an Alert or AlertWindow call.  You can 
  78. then direct the user to the LineEdit control that contains the bad entry by 
  79. calling MakeThisCtlTarget with the handle of that LineEdit control.  This 
  80. deactivates any other target control and moves the insertion point to the 
  81. LineEdit control that needs the correction.
  82.  
  83. Contentious Bits
  84.  
  85. tmContentControls, tmControlMenu and tmControlKey bits are the real workhorses 
  86. of the expanded TaskMaster.
  87.  
  88. When the tmContentControls and tmControlMenu bits are set, TaskMaster handles 
  89. the mouse activity side of events--tracking, highlighting or popping-up the 
  90. selected control.  If the control is a radio button, check box, pop-up menu or 
  91. list control, TaskMaster also performs the correct action for the click, 
  92. either setting the control value, scrolling the list, setting the pop-up menu 
  93. to the selected item, and so on.  TaskMaster then returns a taskCode of 
  94. wInControl ($21).  The control handle is stored in wmTaskData2, the part code 
  95. of the part selected in wmTaskData3 and the control ID is in wmTaskData4.  For 
  96. many of the controls in your windows your application needs to take no further 
  97. actions, TaskMaster has set the control values.  When the user closes the 
  98. window or clicks on a button that causes an action, you can then read the 
  99. values of all the controls you care about at that point and do what you need 
  100. to do, instead of keeping track as the user manipulates controls.
  101.  
  102. The last new bit, tmControlKey, works with the tmControlMenu bit to handle key 
  103. events for your extended controls.
  104.  
  105. When a key event occurs, TaskMaster sends the event to the internal routine 
  106. TaskMasterKey.  TaskMasterKey first looks at the tmMenuKey bit (which has been 
  107. in TaskMaster since the Window Manager was implemented).  If it is set, then 
  108. TaskMaster tries to handle the event as a menu event, calling MenuKey for the 
  109. current menu bar.
  110.  
  111. Note:  This also means that any key equivalents in your main menu bar 
  112.        (across the top of the desktop) take precedence over key 
  113.        equivalents in your window controls.
  114.  
  115. If this fails (or that bit is not set) and tmControlKey is set, then 
  116. TaskMasterKey polls the controls in the currently open window for any controls 
  117. that would like this keystroke, either for controls with a keyEquivalent field 
  118. or a pop-up menu control with key equivalents for menu items.  If it finds a 
  119. control that wants the key event, it is handled very much like a mouse event.  
  120. The action for the control is performed (checking a check box, for example) 
  121. and the wmTaskData fields are filled as they would be for a mouse click, and 
  122. an event code of wInControl ($21) is returned. If a key event did occur, you 
  123. can differentiate it from a mouse event by looking at the wmWhat field of the 
  124. taskRecord.  Even though a wInControl event code was passed back by 
  125. TaskMaster, the wmWhat field is either $0001 or $0003, the former for a mouse 
  126. down event and the latter if a keystroke stimulated the wInControl event.
  127.  
  128. Even More Bits
  129.  
  130. All these new features rely very heavily on the changes made to the Control 
  131. Manager in System Software 5.0.  Many of the TaskMaster features, keystrokes, 
  132. target controls, and so on only work if you have the moreFlags bits set 
  133. correctly in your control definitions.  If you are having difficulty with new 
  134. TaskMaster features, check your control definitions against the information in 
  135. the Control Manager chapter of Volume 3 of the Apple IIgs Toolbox Reference 
  136. and Apple IIgs Technical Note #81, Extended Control Ecstasy.
  137.  
  138.  
  139. Don't Get Goofy
  140.  
  141. There are some dangers in these new features, of course.  By allowing built-in 
  142. key equivalencies for almost all the controls that can exist in a window, it 
  143. may be tempting to define key equivalents for everything, and create weird and 
  144. unusual key combinations for your controls.  Please remember the Human 
  145. Interface Guidelines (specifically Human Interface Note #8, Keyboard 
  146. Equivalents) and keep your use of keystroke equivalents to a minimum.  
  147. Multimodifier keystrokes (Command-Option-Shift, for example) do not enhance 
  148. the user's experience and can be very confusing.
  149.  
  150.  
  151. NDAs Can Have Fun Too
  152.  
  153. TaskMasterDA has also been added to the Window Manager, providing your new 
  154. desk accessories (NDAs) with the same kind of TaskMaster support your 
  155. applications have.  This lets you easily use extended controls inside NDAs, 
  156. following the same basic rules as in an application.  There are only a few 
  157. things to worry about.
  158.  
  159. What Does That Stack Picture Really Mean?
  160.  
  161. The input to TaskMasterDA, as shown in Volume 3 of the Apple IIgs Toolbox 
  162. Reference, is as follows:
  163.  
  164.         |_____________|
  165.         |             |
  166.         |    space    |  word, return space
  167.         |_____________|
  168.         |             |
  169.         |  eventMask  |  word, eventMask, ignore
  170.         |_____________|
  171.         |             |
  172.         |             |
  173.         | taskRecord  |  long, pointer to taskRecord
  174.         |   pointer   |
  175.         |             |
  176.         |_____________|
  177.  
  178.         Figure 1-TaskMasterDA Stack Picture
  179.  
  180. The call returns a word value, the taskCode.  The space and eventMask are 
  181. self-explanatory.  The book tells you that the eventMask is ignored, which 
  182. makes sense since the host application has already gotten the event and you 
  183. have already specified an eventMask in your NDA header, so you can use any 
  184. value here.  The taskRecPointer causes the confusion.
  185.  
  186. You do not pass a blank event record.  When your NDA's action routine is 
  187. called, the Y and X registers contain a pointer to the current event record 
  188. with which the NDA is working.  TaskMasterDA is filling that taskRecord with 
  189. some information, so you want to move it into your NDA's data area so you can 
  190. work with it later:
  191.  
  192.     phy
  193.     phx                   ; push the pointer that was passed to us
  194.     pushlong  #NDArecord  ; the space in my NDA for the extended event record
  195.     pea       0
  196.     pea       16          ; only 16 bytes, the original taskRecord size
  197.     _BlockMove
  198.  
  199. It is very important that you only move 16 bytes.  TaskMasterDA can act 
  200. erratically if the extended portion of the event record has been filled with 
  201. nonsense values.  This can happen if your NDA is running in an application 
  202. that does not use the extended task record and you are copying non-task data 
  203. into the extended portion of the task record.  By the way, as you are 
  204. debugging your NDA and you run into situations where the wmTaskData field 
  205. values are weird, this is more than likely the problem.
  206.  
  207. Also remember to make sure the wmTaskMask field in your NDA's TaskRecord is 
  208. set and the extended portions of the TaskRecord are zeroed out before your NDA 
  209. starts running; you want to set all these fields in your NDA's INIT routine.
  210.  
  211. Now you can call TaskMasterDA:
  212.  
  213.     pea       0           ; return space
  214.     pea       $FFFF       ; eventMask, ignored
  215.     pushlong  #nDArecord  ; our NDA event record
  216.     _TaskMasterDA
  217.     pla                   ; event code returned
  218.  
  219. You can then process the event in a convenient way.  Remember again that 
  220. TaskMaster has already done the control tracking for the controls in your NDA 
  221. window.  You have the same multiclick information, control handles and IDs.
  222.  
  223.  
  224. Conclusion
  225.  
  226. TaskMaster is a wonderful thing that makes any programmer's job easier.  So 
  227. let it work for you.  Learn the capabilities of the new fields and new 
  228. controls, and take advantage of them.  Let TaskMaster take care of the system 
  229. details, while you concentrate on the features that make your application 
  230. special.
  231.  
  232. Further Reference
  233. _____________________________________________________________________________
  234.   o  Apple IIgs Toolbox Reference, Volumes 1 through 3
  235.   o  Apple IIgs Technical Note #81, Extended Control Ecstasy
  236.   o  Human Interface Note #8, Keyboard Equivalents
  237.  
  238.